United Public Domain Gold 4/United Public Domain Gold 4.iso/tbag/tb060.dms/tb060.adf/Docs/Screen_Jaeger.DOCS

Text File | 1991-09-20 | 17KB | 360 lines

 *************************************************************************
 *                                                                       *
 *                           SCREEN JAEGER V1.0                          *
 *                                                                       *
 *  'Jaeger' - German for 'Hunter'. I'm not German, but I like the word. *
 *                                                                       *
 *                        Written by Syd L. Bolton                       *
 *                                                                       *
 *           Copyright ©1991 Legendary Design Technologies Inc.          *
 *                         Freely Redistributable                        *
 *                                                                       *
 *    Source code is included, but may not be used for any commercial    *
 *  use without written permission. Contact information at end of file.  *
 *************************************************************************

INTRODUCTION
~~~~~~~~~~~~

    The Amiga's MultiTasking Operating System is a wonder to behold.
However, many programmers (especially game programmers) for reasons ranging
from ignorance to legitimate speed concerns have often trashed the wonderful
task-switching kernel of our favourite machine.  Many utilities that have
been written on the Amiga are meant to MultiTask and when other programs
don't cooperate, this causes problems for all users.
    A good example of the type of utility I am talking about is
Screen Grabbers.  Many of us are not artists, and we like to fiddle with
DeluxePaint (tm) but grabbing screens from other programs (for personal
use only of course) can save a lot of time and add professionalism to
home videos or other things.  Utilities like GrabbIt (tm) and ScreenX
are great programs, but they MUST be able to work in a MultiTasking
environment.  Many times, this is not able to be done and we can't
grab the screens we would like to.
    Never fear!  Screen Jaeger is here!  Although the concept of
this program is not exactly new, I believe it is the most complete and
flexible program of this type and incorporates many ideas not thought
of before.
    The program works by letting you scan through all available
memory to locate screens.  When you get the mock-up screen exactly
as you want it, you can then save the picture to an IFF file for later
editing or whatever.  The reason it does not need to be in a MultiTasking
environment (although it WILL work in such an environment) is because
when you REBOOT your machine, most memory is still intact, including
screens from the last program you had loaded.  Normally, the system
does not let you access this information, because it is located in the
"free pool" of available memory.  But, usually pictures are there and
you can now make use of them.

PROGRAM REQUIREMENTS
~~~~~~~~~~~~~~~~~~~~

    NOTE: This program REQUIRES the "iff.library" to be located in your
SYS:LIBS: directory.  It should have been included with this distribution
package.  Enter the CLI or SHELL, and enter the sub-directory that
'Screen Jaeger' is in (using the CD command) and then type:

1>copy iff.library sys:libs:

    If you are using a floppy-based WorkBench, you will have to remove
the write-protect tab for this file to be written to your system disk.

    This program is currently approximately 30K (though I am working
on reducing this size) and the screen it opens for itself takes up about
9K for a total of roughly 40K.  Memory usage is important because:

    a) Any memory allocation after the system starts will write OVER
any pictures that may be in memory.  The less allocation you do, the
more chances you have of finding what you are looking for.

    b) The WorkBench screen itself takes up 32K on an NTSC machine,
and 41K on a PAL machine, provided you boot up in NON-INTERLACED mode
(that is, 640X200 NTSC, 2-bitplanes (4 colors)).  This is the recommended
boot-up screen to use.

    c) Because 'Screen Jaeger' uses 40K, a minimum total of 72K of
memory (plus various system pointers and buffers) gets written over.
In most cases this is not tragic since they usually trash lower memory
and game/program screens tend to get loaded higher.

USING SCREEN JAEGER
~~~~~~~~~~~~~~~~~~~

    When you first run the program, you may think something is wrong
with your machine.  The screen you see will most likely be all garbled,
with a small (640 X 56 pixel) window at the bottom of the screen.
(NOTE: This program does support both NTSC and PAL machines, so if you
have a PAL machine the window will be at the VERY bottom of the screen).
What you are seeing is MEMORY!  Screen Jaeger works by letting you change
the pointers of a screen's BITMAPS.  Instead of actually allocating
memory for the screen it just lets you move the pointer(s) around to
wherever you desire.

    The first thing you will probably notice is the four directional
arrows on the left-hand side of the control window.  These can work in
slightly different ways, but are mainly used to control where you are
in memory.  There is a string gadget located nearby called "OFFSET" which
gives you the actual memory location you are currently seeing (starting
of course from the upper-left corner of the display).  You can manually
modify this gadget to jump to a certain position, or use the proportional
gadget to move around, or of course use the arrows.  If you try to access
a memory location too high or too low, the program will automatically
place you at the proper limit.
    When moving through memory if you find that you don't have enough
control with the directional gadgets, try clicking on the "FINE" gadget.
Now, the directional gadgets give you a finer control over the display.
Click "FINE" again to turn this feature off.

    The program defaults to 1 bitplane, but you can easily modify
this by clicking the UP and DOWN "PLANES" gadgets.  You work on only
one bitplane at a time, as highlighted by the gagdets "1" through "6"
in the middle-upper part of the control window.  To change which bitplane
you a working on, just click on the one you desire.  Note of course the
program will not let you click on a bitplane higher than you have currently
specified you will be using.  You can also "SWAP" and "COPY" bitplane
information.  See the explanation of each gadget below for more information.

    Screen Jaeger also allows complete control over the "SCREEN MODES"
to allow you to see a HI-RES, INTERLACE, EXTRA_HALFBRITE, or HAM display.
Note that it is up to the user to determine how many bitplanes and what
type of display is required.  You can also manually control the WIDTH
and HEIGHT of the screen by modifying the string gadgets.

    There is a string gadget which stores the "FILENAME" for saving
purposes.  Because I wanted to keep memory requirements to a minimum,
there is NO file requester.  Instead, just key in the filename, and
include any disk designation if necessary (otherwise, the file will be
sent to the current directory).  Example:

df0:mypicture.pic

    When you click on the SAVE»IFF gadget, your file will be saved
in standard IFF format to the filename specified.  Make sure the filename
is valid.  Any error messages will be directed to the WorkBench screen
in this case, since the SJ screen is too small even for a SYSTEM REQUEST.

CHIP or FAST?
~~~~~~~~~~~~~

    Screen Jaeger is unique in that it also allows you to graphically
look at FAST memory, where graphics can be held but not displayed.  The
way it works is no real trick, it simply allocates the proper amount of
CHIP RAM and then copies the specified FAST RAM down into CHIP where
the video chip can display it.

    NOTE: Never click on the "FAST" gadget until you have retrieved
all that you need from CHIP memory, since some CHIP RAM will have to
be allocated to store the FAST RAM display in.

    Although it must copy memory from FAST down to CHIP, I believe
you will find it quite quick.  I know I was surprised at how fast it
worked.

    The program will show you the upper and lower limits of your
memory (both FAST and CHIP) if you click on the "INFO" gadget.

OVERSCAN SUPPORT
~~~~~~~~~~~~~~~~

    Screen Jaeger is also unique in that it supports overscan!  Since
some applications use various levels of overscan (such as LOW, MEDIUM,
HIGH, SEVERE, etc.) SJ lets you manually control the overscan amount.
You may have to play until you find the "exact" width, but you have
complete flexibility.  To move the display, simply click on the "OVERSCAN"
toggle-gadget.  When you do this, the directional arrows now control
the display offsets.  When you have the screen where you want it, click
the "OVERSCAN" gadget again to revert to normal operation.  Keep in mind
that when you modify the overscan position, you will probably also want
to modify the WIDTH of the screen (from say 320 to 336 or 348).

AUTO BITPLANING
~~~~~~~~~~~~~~~

    Many times you will find one-bitplane of a screen, then another
comes after it, and then another and so on.  To save you the hassle
of setting up each bitplane, you can use the auto-bitplaning procedure
to save time.  Here's how it works:

    a) Set the # of bitplanes to the proper amount.

    b) Work on bitplane #1, and position it in the proper place.

    c) Click on "AUTO".  That's it!

    Your display should now show the entire picture, although chances
are the colors will be all wrong.  Note there is NO way for this program
to retrieve color palette information, since it could be stored ANYWHERE
in memory, and has no real unique way of being identified.
    The auto feature will not work properly if the bitplanes are
scattered in memory, or if the WIDTH and/or HEIGHT are not exactly
as they should be.  For many applications however, it will work and
will save you lots of time.

THE GADGETS IN DETAIL
~~~~~~~~~~~~~~~~~~~~~

The directional arrows: Normally move you through memory quickly.  Can
be modified by other gadgets.

FINE: Makes the directional arrows move the screen in one-pixel increments
(up and down) and one byte (8 pixels) left and right.

OVERSCAN: Makes the directional arrows move the display offsets appropriate-
ly.  Like FINE, it's a toggle gadget so clicking it again will turn it off.

CLR MEM: This gadget will clear the LARGEST chunk of available memory
(FAST or CHIP, whichever is currently selected).  It will NOT wreck
any other applications that are running.  It is useful to run BEFORE you run
the application you are trying to grab a screen from.  It clears out old
information from other programs that may confuse you.

FAST: This gadget turns the display to FAST memory.  NOTE: This will
take away and possibly destroy what's currently in CHIP RAM, so use
this feature only after you have gotten what you need out of CHIP RAM.

CHIP: This feature (the DEFAULT setting) toggles from FAST RAM, and
will deallocate any memory that was needed to display the FAST RAM.

1,2,3,4,5,6: These gadgets simply control which bitplane offset you
are currently working on.  Only one can be active at a time.

AUTO: This gadget tries to automatically line up the necessary number of
bitplanes to form a picture.  See the explanation above for more details.

COPY: This gadget will copy the offset value from the currently selected
bitplane to another.  Clicking COPY again without selecting a second
bitplane to copy to will abort the operation.

SWAP: This gadget will swap the offset values of the currently selected
bitplane with whichever one you click on next. Like copy, clicking a
second time on the SWAP gadget cancels the operation.

HIRES: A toggle gadget which will change the display from 320 to 640
pixels across, and vice versa.

LACE: A toggle gadget which will change the display from 200 to 400
pixels up and down (NOTE: 256 and 512 on PAL systems).

XTRA_HB: Turns on EXTRA_HALFBRITE mode.  Note the program will warn you
if you do not have 6 bitplanes currently selected (which are required
for this mode to function properly).

HAM: Turns on HAM mode.  Like EXTRA_HALFBRITE, this mode requires 6
bitplanes and will be tricky to get a display that looks correct.
However, color assignment is extremely important, so even though
the picture may not look correct, when you edit the colors with something
like Digi-Paint (tm) things should correct themselves.

WIDTH/HEIGHT: These string gadgets let you manually control the width
and the height of the display.  However, the display must be at least
1 pixel in either direction, but not greater than 1024X1024.

INFO: This gadget displays the UPPER and LOWER memory limits of both
your CHIP and FAST RAM (if applicable).  It also tells you the overscan
offsets (so you can check the severity) and also, how much memory the
current display is using. Formula: WIDTH/8*HEIGHT*NUMBER_OF_BITPLANES.
It also displays my name and the version number.

SAVE IFF: This will store the screen into whatever filename is specified
in the string gadget.  MAKE SURE A VALID FILENAME IS IN THE STRING GADGET!

KEYBOARD COMMANDS
~~~~~~~~~~~~~~~~~

    B: Will send the control window to the back (so you can see
       the entire screen). Same as AMIGA-N.

    F: Will send the control window to the front (so you can work
       on the display again). Same as AMIGA-M.

    M: Will move the control window to the top of the display.
           I originally wanted you to be able to view the bottom of the
           screen that the window normally covers up, but you cannot
       do it this way.  I left the code for this in anyway because
           it only took a few bytes!

    N: Moves the control window back to the bottom of the screen.

KNOWN BUGS
~~~~~~~~~~

    The calculation on the PROPORTIONAL GADGET is not 100% correct.
It is a strange formula and I am working (but not TOO hard, since it is
not exactly critical) on fixing this problem.

POSSIBLE ENHANCEMENTS
~~~~~~~~~~~~~~~~~~~~~

    Since I've included the source code, maybe you can add some things
to this program if you deem them useful or necessary (or you can always
call/fax/write me and beg me to do it).  These are a couple of ideas:

    a) Make the overscan controllable just by holding the left button
       down and moving the display in real-time.

    b) Re-write the whole thing in assembler to make it smaller and
       faster (well, I don't want to do it..but ??!?)

    c) Add color-editing so you can make changes without using a paint
       program (though you'll have to get around the problem of the
       number of colors.  The control window display is only 2
       bitplanes (4 colors)).

    d) Squeeze in or create a new "INFO" screen that shows the actual
       offsets for each bitplane.  It's not greatly useful but could
       be interesting.  I originally planned this for INFO but ran
       out of room.

DISCLAIMERS
~~~~~~~~~~~

    a) This software is not guaranteed in any way.  Any liability
concerning the use of this software is completely upon the user. Although
I've never seen it blow up a machine, I am doing some NAUGHTY things.
Anyway, for legal reasons I have to claim NO RESPONSIBILITY.

    b) I do not condone people stealing other people's work for
profit.  The use of this program is for personal entertainment only.
Use the graphics you grab for personal use, or just have fun looking
through memory, but PLEASE DO NOT USE THE GRAPHICS in any other way.
At least contact the company it originated from to ask their permission.

    c) This product is Freely Distributable, but it remains
Copyrighted, ©1991 Legendary Design Technologies Inc.  If you make
modifications to the source code, I would like to hear about it
(especially if it's useful changes).

    d) I don't think my code will win any awards, but it is my code
and I forbid anyone to use any part of it (or the whole thing) in any
commercial product without my written consent.

** THE MOST IMPORTANT NOTE: **

    Keep developers developing!  Buy commercial software, support
shareware, and be thankful to those who contribute public domain and
freely distributable software.  Without these people, what good would
your computer be?
    In my case I am not asking for money (I'll let you pay that for
some of my upcoming commercial products) but you can show your
appreciation in one of two ways:

    a) Donate a little money to the Cancer Society, or some other
       charity.

    b) Fax, Write, or Call me and let me know how this program is
       working for you and what else you'd like to see me write.

For those of you familiar with SCREENMOD, it looks like a VERSION 1.1
is in the works soon!

    Have a good day!  Amiga Rules...

    Syd Bolton
    President
    Legendary Design Technologies Inc.
    25 Frontenac Avenue
    Brantford, Ontario
    N3R 3B7
    (519)-753-6120  Voice/Answering Machine
    (519)-754-4059  Fax